Program Mappings Endpoint

The Program Mappings endpoint delivers mapping information for customers using Gracenote’s VOD Program Services.  The endpoint provides up-to-date information for asset mapping requests received, mappings completed, and assets unable to be mapped. On API can be configured to deliver mapping and program information for one or more customer catalogs.

The ProgramMappings endpoint works in conjunction with the Programs endpoint.  While the ProgramMappings endpoint includes links between TMSIds and customer asset IDs, the Programs endpoint includes the metadata for all referenced TMSIds, including Series records for any referenced Episodes.

Program Mappings endpoint includes a full customer asset catalog, regardless of availability window. Mapping updates reflect changes to any asset mappings, including out-of-window assets if updated due to Gracenote's receipt of new metadata or request for remapping.

The schema provides mapping information, including:

• TmsId, for linking to Programs API
• ProviderId, for linking to customer assets
• Status, for information on mapping stage
• Availability window provided by the customer dataset
• Catalog name, useful for customers providing multiple catalogs for mappings

API and Example Responses

API

http://on-api.gracenote.com/v3/ProgramMappings

?updateId=[updateId value]
&limit=[limit value]
&api_key=[your-api-key]

Request Parameters

Parameter	Required?	Description
api_key	Yes	Your API key
updateId	No	Program mappings modified at or after updateId.
limit	No	Batch size. Maximum number of program mappings to be returned, to be used in conjunction with updateId to specify batch size.
programMappingId	No	For non-batch lookups. Accepts comma-separated list of programMapping IDs.
tmsId	No	For non-batch lookups. 44-char tmsId format. Accepts comma-separated list of TMSIds.
providerId	No	For non-batch lookups. Customer-specific providerId for mappings assets. Accepts comma-separated list of providerIds. Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.

Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.

Example Requests

Return mapping updates in batches of 1000:

http://on-api.gracenote.com/v3/ProgramMappings?updateId=0&limit=1000&api_key=<your-api-key>

Return current mapping data for set of programMappingIds:

http://on-api.gracenote.com/v3/ProgramMappings?programMappingId=28732938,2398237&api_key=<your-api-key>

Example Responses

See Program Mapping XML examples 

Data Structure and Relationships

Schema

Review the following XML schema definition (xsd) to learn about the data structure, fields, and types for this endpoint.

To explore the relationships among all endpoints, see the interactive schema documentation.

XML Schema URL

http://files.api.gracenote.com/xsd/on_update_programmappings_3.24.xsd

The XPATH in the tables below is relative to: on/programMappings/programMapping

XPATH Element/Attribute	Description	Example
@programMappingId	Identifier for the program mapping, uniquely representing customer asset identifier and catalog pair	63940301
catalogName	Name of the catalog containing the program mapping	Disney Plus US
creationDate	Program mapping ingestion/creation date	2020-02-17 08:08:22
status	Mapping status: ToBeMapped, Mapped, Unmappable	Mapped
id@type	GN identifier of a given type: TMSId, rootId, versionId	EP030880640072 (TMSId)
link@idType	Customer asset identifier of a given type: ProviderId, PID (provider id), PAID (provider asset id)	35bb26dd-2f0b-43c1-87e7-486caff60948 (ProviderId)
availability/start	Content provider availability start date and time	2020-03-01T03:00:00Z
availability/end	Content provider availability end date and time	2022-11-12T03:00:00Z
message/@reason	The reason for Unmappable status	Insufficient Metadata, Metadata Discrepancy, Not Included in Current Agreement, Not in Scope for Gracenote Database, …

The Supplemental Controlled Vocabulary (auto-download) provides descriptions and examples for Mapping-related lists.

Entity Relationship Diagram

The ProgramMappings endpoint works in conjunction with the Programs endpoint. The ProgramMappings endpoint contains the links between TMSIds and customer asset identifiers, the Programs endpoint includes the actual metadata for all referenced TMSIds, including Series records for any referenced Episodes.